home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 38 / Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso / -in_the_mag- / reader_requests / dice_v3.15 / doc / time.doc < prev    next >
Text File  |  1999-01-26  |  7KB  |  329 lines
  1.  
  2.     TIME.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/time/asctime
  7. c.lib/time/clock
  8. c.lib/time/ctime
  9. c.lib/time/localtime
  10. c.lib/time/strftime
  11. c.lib/time/time
  12.  
  13.  
  14. time/asctime                        time/asctime
  15.  
  16.    NAME
  17.     asctime - convert broken down time into standard text
  18.  
  19.    SYNOPSIS
  20.     char *str = asctime(ts);
  21.     const struct tm *ts;
  22.  
  23.    FUNCTION
  24.     asctime() converts a broken down time in the tm structure to an
  25.     ascii string and returns a pointer to that string.  The time
  26.     string is formatted like this:
  27.  
  28.         Mon Dec 8 01:53:33 1987\n\0
  29.  
  30.     where \n stands for a newline character and \0 is terminating
  31.     nul.
  32.  
  33.     The string is stored in a static buffer shared by both asctime and
  34.     ctime and so will get overwritten whenever either function is
  35.     called.
  36.  
  37.    EXAMPLE
  38.     /*
  39.      *  since the string returned by asctime already has a newline on
  40.      *  it we use fputs instead puts.
  41.      */
  42.  
  43.     #include <stdio.h>
  44.     #include <time.h>
  45.  
  46.     main()
  47.     {
  48.         time_t t = time(NULL);
  49.         fputs(asctime(localtime(&t)), stdout);
  50.         return(0);
  51.     }
  52.  
  53.    INPUTS
  54.     struct tm *ts;    pointer to a broken down time structure
  55.  
  56.    RESULTS
  57.     char *str;    pointer to static string
  58.  
  59.    SEE ALSO
  60.     time, localtime, asctime, strftime, ctime, clock
  61.  
  62.  
  63. time/clock                        time/clock
  64.  
  65.    NAME
  66.     clock - return system clock value
  67.  
  68.    SYNOPSIS
  69.     clock_t clk = clock(void);
  70.  
  71.    FUNCTION
  72.     clock() returns the system clock in ticks.  To obtain seconds from
  73.     ticks divide the returned value by CLK_TCK in <time.h>
  74.  
  75.    EXAMPLE
  76.     #include <stdio.h>
  77.     #include <time.h>
  78.  
  79.     main()
  80.     {
  81.         clock_t clk = clock();
  82.         long i;
  83.  
  84.         clk = clk + CLK_TCK;
  85.         for (i = 0; clk - clock() > 0; ++i);
  86.         printf("The FOR loop calling clock() took %d loops in one second\n", i);
  87.         return(0);
  88.     }
  89.  
  90.    INPUTS
  91.     none
  92.  
  93.    RESULTS
  94.     clock_t clk;        system clock time value
  95.  
  96.    SEE ALSO
  97.     time, localtime, asctime, strftime, ctime, clock
  98.  
  99.  
  100. time/ctime                        time/ctime
  101.  
  102.    NAME
  103.     ctime - convert time into standard text
  104.  
  105.    SYNOPSIS
  106.     char *str = ctime(&t);
  107.     time_t t;
  108.  
  109.    FUNCTION
  110.     ctime converts a time pointer into ascii text using the following
  111.     format:
  112.  
  113.         Sun Dec 8 01:53:33 1987\n\0
  114.  
  115.     where \n stands for a newline character and \0 is terminating
  116.     nul.
  117.  
  118.     The string is stored in a static buffer shared by both asctime and
  119.     ctime and so will get overwritten whenever either function is
  120.     called.
  121.  
  122.    EXAMPLE
  123.     /*
  124.      *  since the string returned by ctime already has a newline on
  125.      *  it we use fputs instead puts.
  126.      */
  127.  
  128.     #include <stdio.h>
  129.     #include <time.h>
  130.  
  131.     main()
  132.     {
  133.         time_t t = time(NULL);
  134.         fputs(ctime(&t), stdout);
  135.         return(0);
  136.     }
  137.  
  138.    INPUTS
  139.     time_t *t;    pointer to a time_t value
  140.  
  141.    RESULTS
  142.     char *str;    pointer to static string
  143.  
  144.    SEE ALSO
  145.     time, localtime, asctime, strftime, ctime, clock
  146.  
  147.  
  148. time/localtime                        time/localtime
  149.  
  150.    NAME
  151.     localtime - convert time into broken down time
  152.  
  153.    SYNOPSIS
  154.     struct tm *tp = localtime(&t);
  155.     time_t t;
  156.  
  157.    FUNCTION
  158.     localtime takes the address of a time_t variable and breaks up
  159.     the time into component parts, storing them in a static tm
  160.     structure.  The address of this structure is returned.
  161.  
  162.     Since the broken up time is stored into a static structure, the
  163.     structure will get overwritten on the next call to localtime().
  164.  
  165.     The fields of the tm structure are:
  166.  
  167.     struct tm {
  168.         int tm_sec;     /*    0-59    */
  169.         int tm_min;     /*    0-59    */
  170.         int tm_hour;    /*    0-23    */
  171.         int tm_mday;    /*    1-31    */
  172.         int tm_mon;     /*    0-11    */
  173.         int tm_year;    /*    n+1900    */
  174.         int tm_wday;    /*    (sun)0-6*/
  175.         int tm_yday;    /*    0-366    */
  176.         int tm_isdst;   /*    daylight svings time flag (not impl by DICE) */
  177.     };
  178.  
  179.    EXAMPLE
  180.  
  181.     /*
  182.      *  Note that it is much easier to format time/date strings with
  183.      *  strftime().
  184.      */
  185.  
  186.     #include <stdio.h>
  187.     #include <time.h>
  188.  
  189.     main()
  190.     {
  191.         time_t t = time(NULL);
  192.         struct tm *tp = localtime(&t);
  193.  
  194.         printf("The time is %02d:%02d:%02d\n", tp->tm_hour, tp->tm_min, tp->tm_sec);
  195.  
  196.         return(0);
  197.     }
  198.  
  199.    INPUTS
  200.     time_t *t;    pointer to a time_t
  201.  
  202.    RESULTS
  203.     struct tm *tp;    pointer to a struct tm structure filled out according
  204.             to the passed time.
  205.  
  206.    SEE ALSO
  207.     time, localtime, asctime, strftime, ctime, clock
  208.  
  209.  
  210. time/strftime                        time/strftime
  211.  
  212.    NAME
  213.     strftime - convert broken down time into a string according to
  214.            a format.
  215.  
  216.    SYNOPSIS
  217.     size_t len = strftime(buf, max, fmt, tm)
  218.     char *buf;
  219.     size_t max;
  220.     const char *fmt;
  221.     const struct tm *tm;
  222.  
  223.    FUNCTION
  224.     strftime formats a broken down time into a buffer according to
  225.     a format string fmt.  The fmt string looks like a the format for
  226.     a printf except with different control definitions:
  227.  
  228.     %%  - a literal '%' character
  229.     %a  - The locale's abbreviated name for the day of week
  230.     %A  - The locale's full name for the day of week
  231.     %b  - The locale's abbr. name for the month
  232.     %B  - The locale's full name for the month
  233.     %c  - The locale's default representation for the date & time (ctime)
  234.     %d  - The day of the month 01-31
  235.     %H  - The hour 00-23  (24 hour time)
  236.     %I  - The hour 01-12  (12 hour time)
  237.     %j  - The day in the year 001-366
  238.     %m  - The month 01-12
  239.     %M  - The minute 00-59
  240.     %p  - Indication of morning or afternoon.  In the US: "AM" or "PM"
  241.     %S  - The second 00-59
  242.     %U  - The week of the year 00-53, sunday is the first day in a week
  243.     %w  - The day of the week 0-6, sunday=0  (standard)
  244.     %W  - The day of the week 0-6, monday=0
  245.     %x  - The locale's default representation for the date only
  246.     %X  - The locale's default representation for the time only
  247.     %y  - The year mod 100 (00-99)
  248.     %Y  - The full year (e.g. 1990)
  249.     %Z  - The name of the locale's time zone, nothing if unknown
  250.  
  251.     The number of characters written to the string is returned, or 0
  252.     if the formatted string exceeds the buffer size.
  253.  
  254.    WARNING
  255.     There must be at least max + 1 bytes in buf or unexpected memory
  256.     might get overwritten.
  257.  
  258.    EXAMPLE
  259.     #include <stdio.h>
  260.     #include <time.h>
  261.  
  262.     main()
  263.     {
  264.         time_t t = time(NULL);
  265.         struct tm *tp = localtime(&t);
  266.         char buf[256];
  267.  
  268.         strftime(buf, sizeof(buf) - 1, "Now is %A %d %B %Y  %X", tp);
  269.         puts(buf);
  270.  
  271.         return(0);
  272.     }
  273.  
  274.    INPUTS
  275.     char *buf;        buffer to write formatted string into
  276.     size_t max;        maximum size of buffer - 1
  277.     char *fmt;        format string
  278.     struct tm *tm;        broken down time
  279.  
  280.    RESULTS
  281.     size_t len;        length of formatted string in buffer or 0
  282.                 if the maximum was exceeded.
  283.  
  284.    SEE ALSO
  285.     time, localtime, asctime, strftime, ctime, clock
  286.  
  287.  
  288. time/time                        time/time
  289.  
  290.    NAME
  291.     time - get current time
  292.  
  293.    SYNOPSIS
  294.     time_t t = time(NULL);
  295.             or
  296.     time(&t);
  297.     time_t t;
  298.  
  299.    FUNCTION
  300.     time() returns the current time as a time_t and also copies it into
  301.     a time_t if the address of said is passed as an argument.  You may
  302.     pass NULL as an argument in which case the time is only returned.
  303.  
  304.     The time is returned as seconds since some base date, time_t is
  305.     normally an unsigned long.
  306.  
  307.    EXAMPLE
  308.     #include <stdio.h>
  309.     #include <time.h>
  310.  
  311.     main()
  312.     {
  313.         time_t t = time(NULL);
  314.  
  315.         printf("t = %u\n", t);
  316.         return(0);
  317.     }
  318.  
  319.    INPUTS
  320.     time_t *t;    pointer to a time_t or NULL
  321.  
  322.    RESULTS
  323.     time_t t;    a time_t
  324.  
  325.    SEE ALSO
  326.     time, localtime, asctime, strftime, ctime, clock
  327.  
  328.  
  329.